The node-pty package is a Node.js library that provides bindings to pseudo terminals (PTYs). It allows you to spawn and interact with terminal processes programmatically, making it useful for building terminal emulators, remote shells, and other command-line interface (CLI) tools.
Spawning a Terminal Process
This feature allows you to spawn a terminal process. The code sample demonstrates how to spawn a shell process and listen for data events to capture the terminal output.
const pty = require('node-pty');
const shell = process.env[process.platform === 'win32' ? 'COMSPEC' : 'SHELL'];
const ptyProcess = pty.spawn(shell, [], {
name: 'xterm-color',
cols: 80,
rows: 30,
cwd: process.cwd(),
env: process.env
});
ptyProcess.on('data', function(data) {
console.log(data);
});Resizing the Terminal
This feature allows you to resize the terminal window. The code sample shows how to resize the terminal to 100 columns and 40 rows.
ptyProcess.resize(100, 40);Writing to the Terminal
This feature allows you to send input to the terminal process. The code sample demonstrates how to send the 'ls' command to the terminal.
ptyProcess.write('ls\r');xterm is a front-end component that provides a terminal emulator in the browser. It is often used in conjunction with node-pty to create web-based terminal applications. While node-pty handles the backend terminal process, xterm handles the frontend display and interaction.
pty.js is another Node.js library for interacting with pseudo terminals. It is similar to node-pty but is less actively maintained. node-pty is generally preferred due to its better support and more recent updates.
shelljs is a portable Unix shell commands for Node.js. While it does not provide a PTY interface, it allows you to run shell commands and scripts in a more straightforward manner. It is more suitable for simple scripting tasks rather than full terminal emulation.
forkpty(3) bindings for node.js. This allows you to fork processes with pseudoterminal file descriptors. It returns a terminal object which allows reads and writes.
This is useful for:
node-pty supports Linux, macOS and Windows. Windows support is possible by utilizing the Windows conpty API on Windows 1809+ and the winpty library in older version.
The full API for node-pty is contained within the TypeScript declaration file, use the branch/tag picker in GitHub (w) to navigate to the correct version of the API.
var os = require('os');
var pty = require('node-pty');
var shell = os.platform() === 'win32' ? 'powershell.exe' : 'bash';
var ptyProcess = pty.spawn(shell, [], {
name: 'xterm-color',
cols: 80,
rows: 30,
cwd: process.env.HOME,
env: process.env
});
ptyProcess.onData((data) => {
process.stdout.write(data);
});
ptyProcess.write('ls\r');
ptyProcess.resize(100, 40);
ptyProcess.write('ls\r');
node-pty powers many different terminal emulators, including:
Do you use node-pty in your application as well? Please open a Pull Request to include it here. We would love to have it in our list.
# Install dependencies and build C++
npm install
# Compile TypeScript -> JavaScript
npm run build
Node.JS 16 or Electron 19 is required to use node-pty. What version of node is supported is currently mostly bound to whatever version Visual Studio Code is using.
sudo apt install -y make python build-essential
Xcode is needed to compile the sources, this can be installed from the App Store.
npm install requires some tools to be present in the system like Python and C++ compiler. Windows users can easily install them by running the following command in PowerShell as administrator. For more information see https://github.com/felixrieseberg/windows-build-tools:
npm install --global --production windows-build-tools
The following are also needed:
The wiki contains instructions for debugging node-pty.
All processes launched from node-pty will launch at the same permission level of the parent process. Take care particularly when using node-pty inside a server that's accessible on the internet. We recommend launching the pty inside a container to protect your host machine.
Note that node-pty is not thread safe so running it across multiple worker threads in node.js could cause issues.
Automatic flow control can be enabled by either providing handleFlowControl = true in the constructor options or setting it later on:
const PAUSE = '\x13'; // XOFF
const RESUME = '\x11'; // XON
const ptyProcess = pty.spawn(shell, [], {handleFlowControl: true});
// flow control in action
ptyProcess.write(PAUSE); // pty will block and pause the child program
...
ptyProcess.write(RESUME); // pty will enter flow mode and resume the child program
// temporarily disable/re-enable flow control
ptyProcess.handleFlowControl = false;
...
ptyProcess.handleFlowControl = true;
By default PAUSE and RESUME are XON/XOFF control codes (as shown above). To avoid conflicts in environments that use these control codes for different purposes the messages can be customized as flowControlPause: string and flowControlResume: string in the constructor options. PAUSE and RESUME are not passed to the underlying pseudoterminal if flow control is enabled.
Internal Windows PowerShell error. Loading managed Windows PowerShell failed with error 8009001d.
This happens when PowerShell is launched with no SystemRoot environment variable present.
This error can occur due to anti-virus software intercepting winpty from creating a pty. To workaround this you can exclude this file from your anti-virus scanning node-pty\build\Release\winpty-agent.exe
This project is forked from chjj/pty.js with the primary goals being to provide better support for later Node.JS versions and Windows.
Copyright (c) 2012-2015, Christopher Jeffrey (MIT License).
Copyright (c) 2016, Daniel Imms (MIT License).
Copyright (c) 2018, Microsoft Corporation (MIT License).
FAQs
Fork pseudoterminals in Node.JS
We found that node-pty demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket CEO Feross Aboukhadijeh discusses open source security challenges, including zero-day attacks and supply chain risks, on the Cyber Security Council podcast.
Security News
Research
Socket researchers uncover how threat actors weaponize Out-of-Band Application Security Testing (OAST) techniques across the npm, PyPI, and RubyGems ecosystems to exfiltrate sensitive data.
Security News
Research
A malicious npm campaign is targeting Ethereum developers by impersonating Hardhat plugins and the Nomic Foundation, stealing sensitive data like private keys.